Summary

• add a required ci.yml workflow with smart change detection, required-pr, and workflow linting
• add advisory coverage, compatibility, and dependency-audit lanes plus a PR governance workflow and docs link checker script
• update contributor and testing docs to explain the required vs advisory CI lanes
• follow up on workflow and docs-check review hardening, including repo metadata fallback, rename-aware change detection, live label reads, governance body sanitization/serialization, shortcut-reference parsing, and CommonMark fence stripping

Testing

• npm run docs:check
• npm run lint
• npm run typecheck
• npm run build
• npm test
• Not applicable

Docs Impact

• README or docs updated
• No docs changes needed

Compliance Confirmation

• This change stays within the repository scope and OpenAI Terms of Service expectations.
• This change uses official authentication flows only and does not add bypass, scraping, or credential-sharing behavior.
• I updated tests and documentation when the change affected users, maintainers, or repository behavior.
• No auth, request-routing, or storage paths changed.
• I manually tested with a real ChatGPT Plus/Pro account.
• Maintainers can apply the maintainer-live-verified label after independent live verification.

Notes

• Linked issue: none.
• Follow-up work or rollout notes: npm run test:coverage and npm run audit:ci remain advisory because the current baseline still fails the global coverage threshold and reports the existing hono audit issue. This PR also touches .github/pull_request_template.md, so the exempt label is needed for the existing pr-quality workflow.

Summary by CodeRabbit

Release Notes

• Documentation

  • README updated with testing badge and additional contributing resources.
  • Expanded testing documentation with detailed test scenarios and maintainer verification requirements.
  • Improved documentation link validation.

• Tests

  • Added comprehensive test suite for documentation link verification.

• Chores

  • Enhanced CI/CD workflows with improved change detection and conditional job execution.
  • Updated PR templates and governance workflows for compliance tracking.

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

this PR introduces a complete CI/PR automation layer: a required ci.yml workflow with smart rename-aware change detection and a hardened required-pr aggregate gate, advisory pr-advisory.yml lanes for coverage, compat-matrix, and dependency audit, a pr-governance.yml workflow that validates the PR template and manages live-verification labels via pull_request_target, a docs-check.js link validator using only node built-ins, and accompanying docs/template updates.

• all prior review thread issues are addressed: changes and detect-dependency-change both have timeout-minutes: 10, required-pr fails fast when CHANGES_RESULT != "success", HTML comments are stripped before link extraction, and scripts/ci/ changes now trigger docs_changed=true
• pr-governance.yml correctly avoids checking out PR head ref under pull_request_target, uses live label reads via github.paginate, and serialises runs (cancel-in-progress: false) to prevent label race conditions — no windows filesystem or token-safety paths are touched by this PR
• advisory lanes (coverage, compat-matrix, dependency-audit) lack an equivalent DETECT_RESULT guard: if detect-dependency-change fails or is cancelled, all three advisory jobs are silently skipped with no step summary written; since these are unrequired this does not block merge, but silent skips are hard to debug
• getSectionContent in the governance script builds a RegExp from an unescaped heading string — benign with today's hardcoded callers but a latent injection risk if the function is reused
• test/docs-check.test.ts retry cleanup is intentionally broad (retries all errors, not just Windows transient ones), which could leave orphaned tmp/docs-check-* dirs on Windows runners if the retry budget is exhausted by a non-transient error; low severity given runner teardown

Confidence Score: 4/5

• safe to merge — no auth, request-routing, or storage paths changed; previous blocking issues from review threads are resolved
• the required gate hardening (CHANGES_RESULT check, timeouts) and governance workflow correctness (pull_request_target without head checkout, live label reads, serialised concurrency) are all solid. the remaining issues are advisory-lane visibility and a latent regex-injection in a helper function — neither blocks the required CI path or introduces a token/filesystem safety risk on windows
• pr-advisory.yml (silent skip on detect failure) and pr-governance.yml (unescaped regex in getSectionContent)

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant PR as Pull Request
    participant CH as changes job
    participant CJ as code jobs<br/>(lint/typecheck/build/unit-linux/unit-windows)
    participant DS as docs-sanity
    participant AL as actionlint
    participant RP as required-pr gate
    participant PG as pr-governance<br/>(pull_request_target)
    participant AD as advisory lanes<br/>(coverage/compat/audit)

    PR->>CH: trigger on pull_request
    CH->>CH: classify changed files<br/>(code / docs / workflow)
    CH-->>CJ: code_changed=true
    CH-->>DS: docs_changed=true
    CH-->>AL: workflow_changed=true
    CJ-->>RP: result
    DS-->>RP: result
    AL-->>RP: result
    CH-->>RP: CHANGES_RESULT (fail-fast if not success)
    RP->>RP: evaluate gates<br/>exit 1 on any failure
    Note over RP: branch-protection required check

    PR->>AD: trigger (advisory, not required)
    AD->>AD: detect-dependency-change
    AD-->>AD: coverage / compat-matrix / dependency-audit<br/>(continue-on-error: true)

    PR->>PG: pull_request_target<br/>(opened/edited/labeled/sync)
    PG->>PG: fetch live labels via paginate
    PG->>PG: strip code blocks + HTML comments
    PG->>PG: validate template sections + checkboxes
    PG->>PG: detect risky paths (auth/request/storage)
    PG-->>PR: add/remove needs-live-verification label
    PG-->>PR: fail if template incomplete
    Note over PG: branch-protection required check

This is a comment left during a code review.
Path: pr-governance.yml
Line: 123-125

Comment:
**Unescaped heading string used in regex**

`getSectionContent` builds a `RegExp` from the raw `heading` argument without escaping it. today's callers pass hardcoded strings (`"Docs Impact"`, `"Compliance Confirmation"`) that contain no regex-special chars, so this is benign. but if the function is ever reused with an arbitrary heading string (e.g. one containing `.` or `()`), the regex will silently misfire.

```suggestion
            function getSectionContent(markdown, heading) {
              const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
              const headingPattern = new RegExp(`^## ${escapedHeading}\\s*$`, "m");
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: .github/workflows/pr-advisory.yml
Line: 104-108

Comment:
**No failure-propagation guard for `detect-dependency-change`**

unlike `required-pr` in `ci.yml` (which now correctly fails fast when `CHANGES_RESULT != "success"`), the advisory downstream jobs (`coverage`, `compat-matrix`, `dependency-audit`) only gate on the outputs, not on the job result. if `detect-dependency-change` is cancelled or errors out, all three advisory jobs are silently skipped with no indication in the run summary.

since these lanes are explicitly advisory this won't break the required gate, but it does mean a hung or crashed `detect-dependency-change` job produces a deceptively clean advisory run. consider adding a `needs.detect-dependency-change.result == 'success'` guard to each advisory `if:` condition, or a dedicated advisory summary step, so transient runner failures are visible.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: test/docs-check.test.ts
Line: 18-33

Comment:
**Windows temp cleanup silently swallows errors after exhausting retries**

`cleanupTempRoot` retries on any error (not just transient EPERM/EBUSY/EACCES) and logs a warning on final failure — which is intentionally non-fatal. the asymmetry with `runDocsCheckSubprocess`, which only retries windows transient errors, means a genuine non-transient cleanup failure (e.g., permissions on a CI-managed runner dir) will silently leave orphaned `tmp/docs-check-*` dirs under the workspace. these are excluded from git and cleaned by the runner, but they could accumulate across retried CI jobs in the same workflow run. low severity given the `force: true` flag and runner teardown, but worth tracking if you see workspace bloat on the windows compat-matrix lane.

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: d4974b5}